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Foreword 



This Technical Specification has been produced by the 3"^ Generation Partnership Project (3GPP). 

3GPP acknowledges the contribution of the Parlay X Web Services specifications from The Parlay Group. The Parlay 
Group is pleased to see 3GPP acknowledge and publish the present document, and the Parlay Group looks forward to 
working with the 3GPP community to improve future versions of the present document. 

The contents of the present document are subject to continuing work within the TSG and may change following formal 
TSG approval. Should the TSG modify the contents of the present document, it will be re-released by the TSG with an 
identifying change of release date and an increase in version number as follows: 

Version x.y.z 

where: 

X the first digit: 

1 presented to TSG for information; 

2 presented to TSG for approval; 

3 or greater indicates TSG approved document under change control. 

y the second digit is incremented for all changes of substance, i.e. technical enhancements, corrections, 
updates, etc. 

z the third digit is incremented when editorial only changes have been incorporated in the document. 



Introduction 



The present document is part 3 of a multi-part deliverable covering the 3' Generation Partnership Project; Technical 
Specification Group Core Network and Terminals; Open Service Access (OSA); Parlay X Web Services, as identified 
below: 



Part 1: 


"Common"; 


Part 2: 


"Third party call"; 


Part 3: 


"Call Notification"; 


Part 4: 


"Short Messaging"; 


Parts: 


"Multimedia Messaging"; 


Part 6: 


"Payment"; 


Part?: 


"Account management"; 


Part 8: 


"Terminal Status"; 


Part 9: 


"Terminal location"; 


Part 10: 


"Call handling"; 


Part 11: 


"Audio call"; 


Part 12: 


"Multimedia conference"; 


Part 13: 


"Address list management" 


Part 14: 


"Presence". 



£75/ 



3GPP TS 29.1 99-03 version 6.2.0 Release 6 6 ETSI TS 1 29 1 99-3 V6.2.0 (2005-1 2) 

1 Scope 

The present document is Part 3 of the Stage 3 Parlay X Web Services specification for Open Service Access (OS A). 

The OS A specifications define an architecture that enables application developers to make use of network functionality 
through an open standardized interface, i.e. the OSA APIs. The concepts and the functional architecture for the OSA are 
contained in 3GPP TS 23.127 [3]. The requirements for OSA are contained in 3GPP TS 22.127 [2]. 

The present document specifies the Call Notification Web Service aspects of the interface. All aspects of the Call 
Notification Web Service are defined here, these being: 

• Name spaces. 

• Sequence diagrams. 

• Data definitions. 

• Interface specification plus detailed method descriptions. 

• Fault definitions. 

• Service policies. 

• WSDL Description of the interfaces. 

The present document has been defined jointly between 3GPP TSG CT WG5, ETSI TISPAN and The Parlay Group. 

2 References 

The following documents contain provisions which, through reference in this text, constitute provisions of the present 
document. 

• References are either specific (identified by date of publication, edition number, version number, etc.) or 
non-specific. 

• For a specific reference, subsequent revisions do not apply. 

• For a non-specific reference, the latest version applies. In the case of a reference to a 3GPP document (including 
a GSM document), a non-specific reference implicitly refers to the latest version of that document in the same 
Release as the present document. 

[1] 3GPP TR 21.905: "Vocabulary for 3GPP Specifications". 

[2] 3GPP TS 22. 127: "Service Requirement for the Open Services Access (OSA); Stage 1 ". 

[3] 3GPP TS 23. 127: "Virtual Home Environment (VHE) / Open Service Access (OSA); Stage 2". 

[4] 3GPP TS 22.101: "Service aspects; Service principles". 

[5] W3C Recommendation (2 May 2001): "XML Schema Part 2: Datatypes". 

NOTE: Available at http://www.w3.org/TR/2001/REC-xmlschema-2-20010502/ . 

[6] 3GPP TS 29.199-1: "Open Service Access (OSA); Parlay X Web Services; Part 1: Common". 
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3 Definitions and abbreviations 

3.1 Definitions 

For the purposes of the present document, the terms and definitions given in 3GPP TS 29.199-1 [6] apply. 

3.2 Abbreviations 

For the purposes of the present document, the abbreviations given in 3GPP TS 29.199-1 [6] apply. 

4 Detailed service description 

Currently, in order to determine the handling of a subscriber initiated call in telecommunication networks we have to 
write applications using specific protocols to access Call Control functions provided by network elements. This 
approach requires a high degree of network expertise. We can also use the OS A gateway approach, invoking standard 
interfaces to gain access to call control capabilities, but these interfaces are usually perceived to be quite complex by 
application IT developers. Developers must have advanced telecommunication skills to use Call Control OSA 
interfaces. 

In this clause we will describe a Parlay X Web Service, Call Notification, for handling calls initiated by a subscriber in 
the network. A (third party) application determines how the call should be treated. The overall scope of this Web 
Service is to provide simple functions to application developers to determine how a call should be treated. Using the 
Web Services, application developers can perform simple handling of network-initiated calls without specific Telco 
knowledge. 

Examples of usage include the following. 

Incoming call handling: A subscriber receives a call while he is logged-on to the Internet. Since this occupies his 
telephone connection, he is regarded as busy by the network. The subscriber has an application that is invoked when 
somebody tries to call him while he is busy. The application provides the subscriber with a list of choices on how to 
handle the call (e.g. route the call to voicemail, redirect the call to a secretary, reject the call). Based on the response of 
the subscriber the call is handled in the network. Alternatively, the call is re-routed or released depending on the 
preferences of the subscriber and some context information (e.g. based on the status or location of the subscriber). 

Service numbers: An application is triggered whenever a certain service number is dialled. This number is used to 
connect the caller to one of the maintenance personnel. The application redirects the call to the appropriate maintenance 
person based on, e.g. calling party number, time, location and availability of the maintenance personnel. 

SMS notification of missed calls: An application offers the subscriber the possibility to be notified via SMS whenever 
he misses a call. The application registers to be notified when calls to its subscribers encounter busy, no-answer or 
not-reachable. The application does not influence the call treatment, but sends an SMS containing the calling party 
number, the time and reason why the call was missed. 

5 Namespaces 

The CallDirection interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/call_direction/v2_l 
The CallNotification interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/call_notification/v2_l 
The data types are defined in the namespace: 

http://www.csapi.org/schema/parlayx/call_notification/v2_l 
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The CallNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/call_notification/notification_manager/v2_2 
The CallDirectionNotificationManager interface uses the namespace: 

http://www.csapi.org/wsdl/parlayx/call_direction/notification_manager/v2_2 

The 'xsd' namespace is used in the present document to refer to the XML Schema data types defined in XML Schema 
[5]. The use of the name 'xsd' is not semantically significant. 



Sequence diagrams 



6.1 



SMS notification of a missed call 



Showing the use of the Call Notification and Short Messaging Web Services, an SMS is sent to a person who misses a 
call (no answer). This sequence assumes that the provisioning of the 'no answer' call notification has occurred 
independently. 



Application 



Call Notification 
Web Service 



notifyNoAhswerRequest 



"A does not answer"event report (call monitor mode) 



notifyNoAnswerResponse 



sendSmsRequest 



sendSmsResponse 

i-^ 



Short Messaging 
Web Service 
(ref. Part 4) 



Sends an SMS "missed call ' 
notification to A 



Figure 1 
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7 



XML Schema data type definition 



7.1 



ActionValues enumeration 



The ActionValues data type is an enumeration with the following values. 



Enumeration 


Description 


Route 


Request to (re-)route the call to the address indicated with routingAddress. 


Continue 


Request to continue the call without any changes. This will result in normal handling of the event in the 
network. 


EndCall 


Request to end the call. This will result in termination of the call. The callingParty will receive a tone or 
announcement. 



7.2 



Action structure 



The Action data type is a structure containing the following parameters. 



Element name 


Element type 


Optional 


Description 


ActionToPerform 


ActionValues 


No 


Indicates the action as described below 


RoutingAddress 


xsd:anyURI 


No 


The address to be used in case the action indicates 
'Route' 


Charging 


common:Charginglnformation 


Yes 


Charge to apply to this call 



8 



Web Service interface definition 



8.1 



Interface: CallDirection 



This subclause describes an initial set of capabilities in terms of message invocations, parameters and data types. The 
message-based invocations are: 

• handleBusy. 

• handleNotReachable. 

• handleNoAnswer. 

• handleCalledNumber. 

These messages are initiated by the Call Notification Web Service (running in a Parlay X Gateway) and invoke an 
application Web Service(s), as a result of activity in the network. The result of the invocation of a handle<Event> 
operation is used as an indication on how the call should be handled in the network. The application can not keep 
control over the call after handling the event; every event handling is a separate occurrence. 

Note that because the results of the invocations of the application Web Service(s) determine call handling in the 
network, the names of the methods are prefixed with 'handle', rather than 'notify'. The prefix 'notify' would imply a more 
asynchronous behaviour, whereas 'handle' shows the synchronous nature of these invocations. 

The criteria for which the application Web Service(s) should be invoked, such as type of events (busy, answer, etc.), a 
URI to the Web Service and triggered addresses should be provisioned by the operator in an off-line process. 
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8.1.1 Operation: HandleBusy 

The invocation of handleBusy requests the appHcation to inform the gateway how to handle the call between two 
addresses, the callingParty and the calledParty, where the calledParty is busy when the call is received. Optionally, 
the caller"s name is provided. The application returns the action, which directs the gateway to perform one of the 
following actions: 

• "Continue", resulting in normal handling of the busy event in the network, e.g. playing of a busy tone to the 
callingParty. 

• "EndCall", resulting in the call being terminated; the exact tone or announcement that will be played to the 
callingParty is operator-specific. 

• "Route", resulting in the call being re-routed to a calledParty specified by the application. 
Optionally, in the action parameter, the application can also indicate the charging information. 



8.1.1.1 



Input message: handleBusyRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsd:anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party. This party is busy 



8.1.1.2 



Output message: handleBusyResponse 



Partname_ 


Part type 


Optional 


Description 


result 


Action 


No 


It indicates the action to be performed by the gateway 



8.1.1.3 

None. 



Referenced faults 



8.1.2 Operation: HandleNotReaclrable 

The invocation of handleNotReachable requests the application to inform the gateway how to handle the call between 
two addresses, the callingParty and the calledParty, where the calledParty is not reachable when the call is received. 
Optionally, the caller"s name is provided. The application returns the action, which directs the gateway to perform one 
of the following actions: 

• "Continue", resulting in normal handling of the 'not reachable' event in the network, e.g. playing of a busy tone 
to the callingParty. 

• "EndCall", resulting in the call being terminated; the exact tone or announcement that will be played to the 
callingParty is operator-specific. 

• "Route", resulting in the call being re-routed to a calledParty specified by the application. 
Optionally, in the action parameter, the application can also indicate the charging information. 



8.1.2.1 



Input message: handleNotReachableRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsdianyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsdistring 


Yes 


It contains the name of the caller 


CalledParty 


xsdianyURI 


No 


It contains the address of the called party. This party is not reachable 
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8.1.2.2 



Output message: handleNotReachableResponse 



Part name 


Part type 


Optional 


Description 


result 


Action 


No 


It indicates tlie action to be performed by the gateway 



8.1.2.3 

None. 



Referenced faults 



8.1.3 Operation: HandleNoAnswer 

The invocation of handleNoAnswer requests the appHcation to inform the gateway how to handle the call between two 
addresses, the callingParty and the calledParty, where the calledParty does not answer the received call. Optionally, 
the caller"s name is provided. The application returns the action, which directs the gateway to perform one of the 
following actions: 

• "Continue", resulting in normal handling of the 'no answer' event in the network, e.g. playing of a busy tone to 
the callingParty. 

• "EndCall", resulting in the call being terminated; the exact tone or announcement that will be played to the 
callingParty is operator-specific. 

• "Route", resulting in the call being re-routed to a calledParty specified by the application. 
Optionally, in the action parameter, the application can also indicate the charging information. 



8.1.3.1 



Input message: handleNoAnswerRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsd:anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party. This party does not answer 
the call 



8.1.3.2 



Output message: handleNoAnswerResponse 



Part name 


Part type 


Optional 


Description 


result 


Action 


No 


It indicates the action to be performed by the gateway 



8.1.3.3 

None. 



Referenced faults 



8.1.4 Operation: HandleCalledNumber 

The invocation of handleCalledNumber requests the application to inform the gateway how to handle the call between 
two addresses, the callingParty and the calledParty. The method is invoked when the callingParty tries to call the 
calledParty, but before the network routes the call to the calledParty. For example, the calledParty does not have to 
refer to a real end user, i.e., it could be a service number. Optionally, the caller"s name is provided. The application 
returns the action, which directs the gateway to perform one of the following actions: 

• "Continue", resulting in normal handling in the network, i.e. the call will be routed to the calledParty number, as 
originally dialled. 

• "EndCall", resulting in the call being terminated; the exact tone or announcement that will be played to the 
callingParty is operator-specific. 

• "Route", resulting in the call being re-routed to a calledParty specified by the application. 
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Optionally, in the action parameter, the application can also indicate the charging information. 

8.1 .4.1 Input message: handleCalledNumberRequest 



Part name 


Part type 


Optional 


Description j 


CallingParty 


xsd:anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party 



8.1.4.2 



Output message: handleCalledNumberResponse 



Part name 


Part type 


Optional 


Description 


result 


Action 


No 


It indicates the action to be performed by the gateway 



8.1.4.3 

None. 



Referenced faults 



8.2 



Interface: CallNotification 



When call events occur in the network, the application may be notified of these events. The application does not have 
the ability to influence the call, as call processing continues. 

Notifications are provided for call attempt, busy, not reachable and no answer events. 

8.2.1 Operation: NotifyBusy 

A busy notification informs the application that a call between two parties was attempted, but the called party was busy. 



8.2.1.1 



Input message: NotifyBusyRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsd:anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party. This party is busy 



8.2.1.2 



Output message: NotifyBusyResponse 



Part name 


Part type 


Optional 


Description 


None 




No 





8.2.1.3 

None. 



Referenced faults 



8.2.2 Operation: NotifyNotReacinable 



A not reachable notification informs the application that a call between two parties was attempted, but the called party 
was not reachable. 
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8.2.2.1 



Input message: NotifyNotReachableRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsd;anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party. This party is not reachable 



8.2.2.2 



Output message: NotifyNotReachableResponse 



Part name 


Part type 


Optional 


Description 


None 




No 





8.2.2.3 

None. 



Referenced faults 



8.2.3 Operation: NotifyNoAnswer 



A no answer notification informs the application that a call between two parties was attempted, but the called party did 
not answer. 



8.2.3.1 



Input message: NotlfyNoAnswerRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsd:anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party. This party did not answer 


8.2.3.2 Output message: NotifyNoAnswerResponse 


Part name 


Part type 


Optional 


Description 


None 




No 





8.2.3.3 

None. 



Referenced faults 



8.2.4 Operation: NotifyCalledNumber 

A called number notification informs the application that a call between two parties is being attempted. 



8.2.4.1 



Input message: NotifyCalledNumberRequest 



Part name 


Part type 


Optional 


Description 


CallingParty 


xsd:anyURI 


No 


It contains the address of the caller 


CallingPartyName 


xsd:string 


Yes 


It contains the name of the caller 


CalledParty 


xsd:anyURI 


No 


It contains the address of the called party 



8.2.4.2 



Output message: NotifyCalledNumberResponse 



Part name 


Part type 


Optional 


Description j 


None 




No 
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8.2.4.3 

None. 



Referenced faults 



8.3 Interface: CallNotificationManager 

The call notification manager enables applications to set up and tear down notifications for calls online. 

8.4.1 Operation: StartCallNotification 

Start notifications to the application for a given address. The address is an Address Data item as defined in 3GPP TS 
29.199-1 [6]. 

The correlator provided in the reference must be unique for the application Web Service at the time the notification is 
initiated, otherwise a ServiceException (SVC0005) will be returned to the application.. 



8.4.1.1 



Input message: StartCallNotification Request 



Part name 


Part type 


Optional 


Description 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Address 


xsd:anyURI 


No 


Address to receive notifications on 



8.4.1.2 



Output message: StartCallNotificationResponse 



Part Name 


Part Type 


Optional 


Description 


none 









8.4.1.3 Referenced Faults 

ServiceException from [6] 

• SVCOOOl - Service error 

• SVC0002 - Invalid input value 

• SVC0005 - Duplicate correlator 
PolicyException from [6] 

• POLOOOl- Policy error 

8.4.2 Operation: StopCallNotification 

The application may end a call notification using this operation 

8.4.2.1 Input message: StopCallNotification Request 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator of request to end 



8.4.2.2 



Output message: StopCallNotification Response 



Part Name 


Part Type 


Optional 


Description 


None 
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8.4.2.3 Referenced Faults 

ServiceException from [6] 

• SVCOOOl - Service error 

• SVC0002 - Invalid input value 
PolicyException from [6] 

• POLOOO 1 - Policy error 

8.4 Interface: CallDirectionManager 

The call direction manager enables applications to set up and tear down notifications for calls online. 

8.4.1 Operation: StartCallDirectionNotification 

Start notifications to the application for a given address. The address is an Address Data item as defined in 3GPP TS 
29.199-1 [6]. 

The correlator provided in the reference must be unique for the application Web Service at the time the notification is 
initiated, otherwise a ServiceException (SVC0005) will be returned to the application.. 



8.4.1.1 



Input message: StartCallDlrectionNotificationRequest 



Part name 


Part type 


Optional 


Description ^ 


Reference 


common:SimpleReference 


No 


Notification endpoint definition 


Address 


xsd:anyURI 


No 


Address to receive notifications on 



8.4.1.2 



Output message: StartCallDlrectionNotificatlonResponse 



Part Name 


Part Type 


Optional 


Description 


none 









8.4.1.3 Referenced Faults 

ServiceException from [6] 

• SVCOOOl - Service error 

• SVC0002 - Invalid input value 

• SVC0005 - DupHcate correlator 
PolicyException from [6] 

• POLOOO 1 - Policy error 

8.4.2 Operation: StopCallDirectionNotification 

The application may end a call notification using this operation 



£75/ 



3GPP TS 29.199-03 version 6.2.0 Release 6 



16 



ETSI TS 129 199-3 V6.2.0 (2005-12) 



8.4.2.1 



Input message: StopCallDirectionNotificationRequest 



Part name 


Part type 


Optional 


Description 


Correlator 


xsd:string 


No 


Correlator of request to end 



8.4.2.2 



Output message: StopCallDirectionNotificationResponse 



Part Name 


Part Type 


Optional 


Description 


None 









8.4.2.3 Referenced Faults 

ServiceException from [6] 

• SVCOOOl - Service error 

• SVC0002 - Invalid input value 
PolicyException from [6] 

• POLOOOl - Policy error 



Fault definitions 



No new faults defined for this service. 



10 Service policies 

No service policies are defined for this service. 
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Annex A (normative): 
WSDL for call notification 



The document/literal WSDL representation of this interface specification is compliant to 3GPP TS 29.199-1 [6] and is 
contained in text files (contained in archive 29199-03-620-doclit.zip) which accompanies the present document. 
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Annex B (informative): 
Change history 



Change history 


Date 


TSG# 


TSG Doc. 


CR 


Rev 


Subject/Comment 


Old 


New 


Dec 2003 


CN 21 


NP-030552 


-- 


-- 


Submitted to CN#22 for Information 


1.0.0 




Jan 2004 










Added The W3C WSDL representation of the APIs specified in the 
present document is contained in a set of files which accompany the 
present document: 

px0326rpcenc.zip 

px0326rpclit.zip 


1.0.1 




Jun 2004 


CN_24 


NP-040274 


- 


- 


Split into multi-part specification. 29.199-On, for n=1,2...9. 
Submitted to CN#24 for Information 


1.0.3 




Sep 2004 


CN 25 


NP-040360 


-- 


-- 


Draft v200 submitted to TSG CN#25 for Approval. 


2.0.0 


6.0.0 


Jun 2005 


CT 28 


CP-050159 


0001 


-- 


Incorrect method names in WSDL files for Call Notification Interface 


6.0.0 


6.1.0 


Jun 2005 


CT 28 


CP-050159 


0002 


-- 


Add display name data 


6.0.0 


6.1.0 


Jun 2005 


CT 28 


CP-050221 


0003 


-- 


Optionals for Part 3 


6.0.0 


6.1.0 


Dec 2005 


CT 30 


CP-050567 


0004 


-- 


Clarify sequence diagram 


6.1.0 


6.2.0 


Dec 2005 


CT 30 


CP-050567 


0005 


-- 


Correction to Call Notification for missing management interface 


6.1.0 


6.2.0 


Dec 2005 


CT 30 


CP-050567 


0006 


-- 


Inconsistent part naming in PX response messages 


6.1.0 


6.2.0 
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History 



Document history 


V6.0.0 


January 2005 


Publication 


V6.1.0 


June 2005 


Publication 


V6.2.0 


December 2005 


Publication 
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